近期從產品經理轉職為 Technical Writer，為了加強自己的技術寫作能力，我決定將自己學習技術寫作的過程記錄下來。

關於 Technical Writing 的學習資源非常多，我研究了 Google Technical Writing, Gitlab Technical Writing 以及 Amazon 上的書籍。最終決定先從 WRITE THE DOCS 這個學習資源起手，它是目前我看到學習資源最豐富的網站。

這篇先從 《A beginner’s guide to writing documentation》開始。

為什麼要寫技術文件 ?

主要有 5 個原因

1. 6 個月後你還會使用到自己寫的程式碼

6 個月後我們會忘記當初為什麼寫下這段程式碼，寫文件是幫助未來的自己恢復記憶。

在紀錄文件的過程中，我們寫下了 why (為什麼) 這段程式碼要這樣作，幫助我們理清思緒。

為了讓自己在未來看得懂，我們間接的培養照顧讀者 (care your readers) 的心態。

2. 你想要別人使用你的程式碼

身為開發者，我們想要其他人使用我們的程式碼，但前提是必須讓人理解「用你的程式碼有什麼好處」。
別人要如何使用你的程式碼呢？他們必須看得懂

• 這段程式碼可以達成什麼目的
• 如何安裝你的程式碼
• 了解與會使用你的程式碼

如果你愛護自己的專案，就需要寫清楚文件。

3. 你想要別人幫助你

當我們成為 Open Source 軟體開發者時，總會希望有 contributor。

Contribute 只發生在 Open Source 有使用者、有文件、放了很多心力的情況下。

4. 你想要讓程式碼寫的更好

寫文件能幫助自己設計程式。

例如在替 API 寫說明文件時，寫下自己為什麼要這樣設計，能幫助自己思考。

5. 你想要成為一個更好的 writer

寫文件就是在做長期的寫作肌肉訓練，愈寫愈好、愈不寫愈難重新啟動。

如何開始寫技術文件 ?

從簡單的步驟開始:

• 用列點寫大綱
• 從 README 開始
• 從使用 markup language (標記語言) 開始

慢慢培養寫作肌肉，養成寫文件的習慣。

技術文件要寫給誰看?

從簡單開始，只需要先瞄準 2 種人:

• User
• Developer

前者只管如何使用 (how) 但不管程式碼如何運作;後者想要 contribute 因此需要了解 Code 的運作方式。

文件要寫什麼 ?

寫以下內容:

1. 這個專案要解決什麼問題: 參考例子 Python Library designed to execute shell commands remotely over SSH- Fabric

2. 一小段程式碼展示這個專案的功能: 參考例子 HTTP library for Python

3. 程式碼和 issue tracker 的連結: 參考例子 The Hitchhiker’s Guide to Python

4. 常見問題 (FAQ): 參考例子 Tastypie Cookbook

5. 使用中碰到困難時如何取得協助: 常見方式有 Mail, Community, IRC Channel, 通訊軟體 (Discord/ Slack...)。參考例子 FAQ: Getting Help | Django documentation

6. 其他人如何 contribute: 參考例子 Contributing — OpenComparison documentation

7. 安裝指南: 參考例子 Installation — Read the Docs 2.7 documentation

8. 專案授權形式 (Project license): 可使用 Open Source Project license 快速查詢網站: Chooselicense

參考資源

A beginner’s guide to writing documentation